//
//  "$Id: FlashLamp.h 98676 2013-01-21 06:41:29Z hao_shiming $"
//
//  Copyright (c)1992-2009, ZheJiang Dahua Technology Stock CO.LTD.
//  All Rights Reserved.
//
//	Description:	闪光灯接口
//	Revisions:		Year-Month-Day  SVN-Author  Modification
//

#ifndef __FLASHLAMP_API_H__
#define __FLASHLAMP_API_H__

#include  "Types.h"
#include "Defs.h"

#ifdef __cplusplus
extern "C" {
#endif

/// \defgroup flashLampAPI API flashLamp
/// 闪光灯操作接口
///	\n 调用流程图:
/// \code
///    ===========================
///                |
///        *createFlashLamp
///                |
///             addRef
///                |
///             getCaps
///                |
///              flash
///                |
///             release
///                |
///    ===========================
/// \endcode
/// @{

/// 闪光灯设备特性结果，128字节
typedef struct FlashLampCaps
{
	char	powerMode;				///< 是否支持电源控制，0-不支持，1-支持
	int		maxDelayTime;			///< 爆闪灯(频闪灯)最大延迟时间，单位 us，负数表示提前
	uint	maxPlusWidthTime;		///< 爆闪灯(频闪灯)最大脉宽时间，单位us
	int		frequencyNumber;		///< 频闪灯支持的频率数量；
	int		*frequencys;			///< 支持的频率的数组
	int		minDelayTime;			///< 爆闪灯(频闪灯)最小延迟时间，单位 us，负数表示提前
	int		reserved[26];			///< 保留
}FlashLampCaps;

/// 闪光灯类型枚举
typedef enum FlashLampType
{
	flashLampTypeStroboscopic = 0,	///< 频闪灯
	flashLampTypeFlash				///< 爆闪灯
}FlashLampType;

/// 工作模式
typedef enum BaokangCameraLampMode
{
	baokangCameraLampClose = 0,		//始终关闭
	baokangCameraLampOpen,			//始终开启
	baokangCameraLampAuto,			//自动	
} BaokangCameraLampMode;

///宝康相机灯光配置
typedef struct BaokangCameraLampConfig
{
	BaokangCameraLampMode					mode : 8;						///<灯光工作模式
	int										value : 16;						///<亮度工作值	单位为us; 100us-10000us
	//int									reservedBits : 8;				///<保留位
	float									exposalSynchronizationTime;		///<曝光同步时间	单位为ms;  -6.00ms~ 6.00ms
	//int 									reserved[6];					///<保留
}BaokangCameraLampConfig;

///相机灯光配置 32字节
typedef union CameraLampConfig
{
	BaokangCameraLampConfig		baokanConfig;		///<宝康相机灯光配置 
	int 						placeholder[8];		///< 占位符，保证这个联合体体为32字节
}CameraLampConfig;


/// 爆闪灯、频闪灯的工作模式
typedef enum CameraFlashMode
{
	cameraFlashModeClsoe = 0,		///< 关闭模式
	cameraFlashModeOpen,			///< 打开模式
	cameraFlashModeAuto				///< 自动模式
}CameraFlashMode;


///< 爆闪灯、频闪灯的设置参数，256字节
typedef struct CameraFlashOptions
{
	int					delayTime;			///< 爆闪灯/频闪灯延时闪时间，单位 us
	uint				frequency;			///< 频闪灯的工作频率, 单位 HZ, 譬如50HZ, 100HZ
	uint 				flashValue;			///< 爆闪灯/频闪灯闪光灯时间，us为单位；
	uchar				preValue;			///< 爆闪灯/频闪灯亮度阈值预设值，环境亮度低于此值开启闪光灯，取值范围[0, 100]
	uchar				pole;				///< 爆闪灯触发模式，0-低电平 1-高电平 2-上升沿 3-下降沿
	uchar				dutyCycle;			///< 频闪灯占空比，范围0~100
	uchar				frequencyMultiple;	///< 频闪灯倍频，范围0~10
	int					reserved[60];		///< 保留字节
}CameraFlashOptions;

/// 闪光灯接口，512字节
typedef struct FlashLamp
{
	/// 底层似有数据
	void *priv;
	
	/// 增加接口引用
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \retval 0 成功
	/// \retval <0失败
	int (*addRef)(struct FlashLamp *thiz);
	
	/// 释放接口
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \retval 0 成功
	/// \retval <0失败
	
	int (*release)(struct FlashLamp *thiz);
	/// 获取闪光灯能力
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [out] caps 闪光灯特性结构FlashLampCaps指针
	/// \retval 0 获取成功
	/// \retval <0 获取失败
	int (*getCaps)(struct FlashLamp *thiz, FlashLampCaps *caps);
	
	/// 闪光灯电源控制
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [in] state 电源操作，0-关闭电源，1-打开电源
	/// \retval 0 成功
	/// \retval <0失败
	int (*setPowerMode)(struct FlashLamp *thiz, int state);
	
	/// 获取闪光灯电源状态
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [out] state 闪光灯电源状态，0-关闭，1-上电
	/// \retval 0 成功
	/// \retval <0 失败
	int (*getPowerMode)(struct FlashLamp *thiz, int *state);
	
	/// 控制闪光灯闪光
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [in] onCycle 闪光时间，单位us
	/// \param [in] offCycle 熄灭时间，单位us
	/// \param [in] frequency 闪光频率，单位hz，为0表示只闪一次
	/// \retval 0 成功
	/// \retval <0 失败
	int (*flash)(struct FlashLamp *thiz, int onCycle, int offCycle, int frequency);
	
	/// 配置相机灯光参数
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [in] count  ，数组成员个数
	/// \param [in] lampConfig 配置参数，是个数组，数组成员个数，由count指定	
	/// \retval 0 成功
	/// \retval <0 失败
	int (*setCameraLampConfig)(struct FlashLamp *thiz, int count, CameraLampConfig * lampConfig);
	
	/// 配置闪光灯(频闪灯)工作模式
	///
	/// \param [in] thiz 闪光灯接口指针
	/// \param [in] CameraFlashMode 相机闪光灯工作模式
	/// \retval 0 成功
	/// \retval <0 失败
	int (*setWorkMode)(struct FlashLamp *thiz, CameraFlashMode mode);
	
	/// 配置频闪灯的参数  
	///
	/// \param [in] thiz 灯接口指针
	/// \param [in] options 配置参数，是个数组，数组成员个数，由count指定	
	/// \retval 0 成功
	/// \retval <0 失败
	int (*setCameraFlashOption)(struct FlashLamp *thiz, CameraFlashOptions * options);
	
	/// 保留字节
	int reserved[118];
}FlashLamp;

/// 闪光灯接口描述结构，128字节
typedef struct FlashLampDesc
{
	int				port;			///< 闪光灯编号
	FlashLampType	type;			///< 闪光灯类型
	int				reserved[30];	///< 保留字节
}FlashLampDesc;

/// 创建闪光灯接口
///
/// \param [in] desc，闪光灯接口描述指针
/// \param [in] lamp，闪光灯接口指针的指针
/// \retval 0 成功
/// \retval <0 失败
int PAL_API createFlashLamp(FlashLampDesc *desc, FlashLamp **lamp);

/// 得到闪光灯数目
///
/// \retval 闪光灯数目
int PAL_API getFlashLampCount(void);

/// @} end of group
#ifdef __cplusplus
}
#endif

#endif //__FLASHLAMP_API_H__

